/**
 * chenuu.com
 * 
 * @author  zhaoxu.com@gmail.com
 * @created 2012-11-10
 */
package com.chenuu.integration.httpclient.dropbox;

import com.dropbox.client2.exception.DropboxException;
import com.dropbox.client2.exception.DropboxIOException;
import com.dropbox.client2.exception.DropboxPartialFileException;
import com.dropbox.client2.exception.DropboxServerException;

/**
 * A request to upload a file to Dropbox.  This request can be canceled
 * by calling abort().
 */
public interface UploadRequest {
    /**
     * Aborts the request. The original call to upload() will throw a
     * {@link DropboxPartialFileException}.
     */
    public void abort();

    /**
     * Executes the request.
     *
     * @return an {@link Entry} representing the uploaded file.
     *
     * @throws DropboxPartialFileException if the request was canceled
     *         before completion.
     * @throws DropboxServerException if the server responds with an error
     *         code. See the constants in {@link DropboxServerException} for
     *         the meaning of each error code. The most common error codes
     *         you can expect from this call are 404 (path to upload not
     *         found), 507 (user over quota), and 400 (unexpected parent
     *         rev).
     * @throws DropboxIOException if any network-related error occurs.
     * @throws DropboxException for any other unknown errors. This is also a
     *         superclass of all other Dropbox exceptions, so you may want to
     *         only catch this exception which signals that some kind of error
     *         occurred.
     */
    public DropboxEntry upload() throws DropboxException;
}